Fix KeybindingHint key display on non-MacOS/Windows platforms by jonrohan · Pull Request #7908 · primer/react

jonrohan · 2026-05-29T22:30:10Z

Here's a preview of all the modifier keys on different platforms https://primer-11d74e8128-13348165.drafts.github.io/storybook/?path=/story/experimental-components-keybindinghint-features--platforms

KeybindingHint previously only distinguished between MacOS and "not MacOS" when displaying the Meta, Alt, and Mod keys. As a result, the Meta key was rendered as Win (Windows key) on Linux, Android, and other platforms where that key does not exist.

This change introduces a three-way platform detection (mac / windows / other) so keys are displayed correctly per platform.

Changelog

New

Added an SSR-safe usePlatform() hook (internal to KeybindingHint) that returns 'mac' | 'windows' | 'other'. Apple platforms (macOS and iOS/iPadOS) map to 'mac'.

Changed

KeybindingHint now resolves platform-specific keys based on the detected platform:
- Meta: ⌘/Command on Apple, Win/Windows on Windows, Meta on all other platforms.
- Alt: ⌥/Option on Apple, Alt elsewhere.
- Mod: ⌘/Command on Apple, ⌃/Control elsewhere.
getAccessibleKeybindingHintString remains backward compatible — it still accepts the previous boolean argument (true → 'mac', false → 'other') in addition to a Platform value.

Removed

N/A

Rollout strategy

Patch release

Testing & Reviewing

Unit tests were added covering Meta, Alt, and Mod rendering across all three platform categories. Existing KeybindingHint, Tooltip, and TreeView tests pass.

Merge checklist

changeset-bot · 2026-05-29T22:30:16Z

🦋 Changeset detected

Latest commit: 4cb7c0e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@primer/react	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2026-05-29T22:30:41Z

⚠️ Action required

👋 Hi, this pull request contains changes to the source code that github/github-ui depends on. If you are GitHub staff, test these changes with github/github-ui using the integration workflow. Check the integration testing docs for step-by-step instructions. Or, apply the integration-tests: skipped manually label to skip these checks.

To publish a canary release for integration testing, apply the Canary Release label to this PR.

Copilot

Pull request overview

This PR updates KeybindingHint platform handling so modifier keys are displayed appropriately on Apple, Windows, and other platforms, addressing Linux/Android Meta key labeling.

Changes:

Added internal tri-state platform detection and platform override support for Storybook previews.
Updated KeybindingHint, TooltipV2, and TreeView to use platform-aware key naming.
Added accessible-string tests and a Storybook matrix for platform-specific modifier rendering.

Show a summary per file

File	Description
`packages/react/src/TreeView/TreeView.tsx`	Uses the new platform hook for TreeView shortcut labels.
`packages/react/src/TooltipV2/Tooltip.tsx`	Uses platform-aware accessible shortcut descriptions.
`packages/react/src/KeybindingHint/platform.ts`	Adds platform detection and override context.
`packages/react/src/KeybindingHint/KeybindingHint.tsx`	Updates accessible helper to accept platform values.
`packages/react/src/KeybindingHint/KeybindingHint.test.tsx`	Adds accessible-name coverage for platform-specific keys.
`packages/react/src/KeybindingHint/KeybindingHint.features.stories.tsx`	Adds a platform comparison Storybook story.
`packages/react/src/KeybindingHint/KeybindingHint.features.stories.module.css`	Styles the new platform comparison table.
`packages/react/src/KeybindingHint/key-names.ts`	Implements platform-specific key-name mappings.
`packages/react/src/KeybindingHint/components/Sequence.tsx`	Threads platform values through accessible sequence strings.
`packages/react/src/KeybindingHint/components/Key.tsx`	Renders keys using detected platform mappings.
`packages/react/src/KeybindingHint/components/Chord.tsx`	Threads platform values through accessible chord strings.
`.changeset/keybinding-hint-platform-keys.md`	Adds a patch changeset for the behavior fix.

Copilot's findings

Files reviewed: 12/12 changed files
Comments generated: 1

    shift: '⇧',
-    meta: isMacOS ? '⌘' : 'Win',
-    mod: isMacOS ? '⌘' : '⌃',
+    meta: platform === 'mac' ? '⌘' : platform === 'windows' ? 'Win' : 'Meta',


github-actions · 2026-05-29T23:18:26Z

Uh oh! @jonrohan, at least one image you shared is missing helpful alt text. Check your pull request body to fix the following violations:

Images should have meaningful alternative text (alt text) at line 5
Images should have meaningful alternative text (alt text) at line 7

Alt text is an invisible description that helps screen readers describe images to blind or low-vision users. If you are using markdown to display images, add your alt text inside the brackets of the markdown image.

Learn more about alt text at Basic writing and formatting syntax: images on GitHub Docs.

🤖 Beep boop! This comment was added automatically by github/accessibility-alt-text-bot.

primer-integration · 2026-05-29T23:43:10Z

👋 Hi from github/github-ui! Your integration PR is ready: https://github.com/github/github-ui/pull/21980

primer-integration · 2026-05-30T00:04:27Z

Integration test results from github/github-ui:

CI Passed
VRT Running
Projects Passed

iansan5653 · 2026-06-01T14:53:43Z

useIsMacOS is a common, shared utility hook. Should usePlatform live in the same place? Or maybe we should just update that hook to be more powerful? Seems like this could be useful for other components.

iansan5653 · 2026-06-01T14:55:10Z

+ * `'other'`.
 */
-export const getAccessibleKeybindingHintString = accessibleSequenceString
+export const getAccessibleKeybindingHintString = (sequence: string, platform: Platform | boolean) =>


A followup task after release should be to update consumers in github/github to use the new Platform type instead of boolean

iansan5653 · 2026-06-01T14:57:41Z

+ * - `other`: Any other platform (e.g. Linux, Android), where the Meta key does not map to a
+ *   consistent label.
+ */
+export type Platform = 'mac' | 'windows' | 'other'


[nit] Would it be clearer to rename mac to apple? Since iOS/iPadOS aren't Mac OSes.

TylerJDev

LGTM! +1 to Ian's comments, though approving ahead of time.

Fix KeybindingHint key display on non-MacOS/Windows platforms

7a7da00

github-actions Bot added staff Author is a staff member integration-tests: recommended This change needs to be tested for breaking changes. See https://arc.net/l/quote/tdmpakpm labels May 29, 2026

jonrohan deployed to github-pages May 29, 2026 22:41 — with GitHub Actions View deployment

github-actions Bot temporarily deployed to storybook-preview-7908 May 29, 2026 22:42 Inactive

Add story demonstrating modifier keys across platforms

4cb7c0e

jonrohan marked this pull request as ready for review May 29, 2026 23:05

jonrohan requested a review from a team as a code owner May 29, 2026 23:05

jonrohan requested review from TylerJDev and Copilot May 29, 2026 23:05

Copilot started reviewing on behalf of jonrohan May 29, 2026 23:06 View session

Copilot AI reviewed May 29, 2026

View reviewed changes

Comment thread packages/react/src/KeybindingHint/key-names.ts

shift: '⇧',

meta: isMacOS ? '⌘' : 'Win',

mod: isMacOS ? '⌘' : '⌃',

meta: platform === 'mac' ? '⌘' : platform === 'windows' ? 'Win' : 'Meta',

jonrohan deployed to github-pages May 29, 2026 23:16 — with GitHub Actions View deployment

github-actions Bot deployed to storybook-preview-7908 May 29, 2026 23:16 View deployment

jonrohan requested a review from iansan5653 May 29, 2026 23:18

jonrohan added the Canary Release Apply this label when you want CI to create a canary release of the current PR label May 29, 2026

iansan5653 approved these changes Jun 1, 2026

View reviewed changes

TylerJDev approved these changes Jun 1, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Fix KeybindingHint key display on non-MacOS/Windows platforms#7908

Fix KeybindingHint key display on non-MacOS/Windows platforms#7908
jonrohan wants to merge 2 commits into
mainfrom
fix-keybinding-hint-platform-keys

jonrohan commented May 29, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented May 29, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 29, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

github-actions Bot commented May 29, 2026 •

edited

Loading

Uh oh!

primer-integration Bot commented May 29, 2026

Uh oh!

primer-integration Bot commented May 30, 2026

Uh oh!

iansan5653 Jun 1, 2026

Uh oh!

iansan5653 Jun 1, 2026

Uh oh!

iansan5653 Jun 1, 2026

Uh oh!

TylerJDev left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

jonrohan commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changelog

New

Changed

Removed

Rollout strategy

Testing & Reviewing

Merge checklist

Uh oh!

changeset-bot Bot commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions Bot commented May 29, 2026

⚠️ Action required

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

github-actions Bot commented May 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

primer-integration Bot commented May 29, 2026

Uh oh!

primer-integration Bot commented May 30, 2026

Uh oh!

iansan5653 Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

iansan5653 Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

iansan5653 Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

TylerJDev left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

jonrohan commented May 29, 2026 •

edited

Loading

changeset-bot Bot commented May 29, 2026 •

edited

Loading

github-actions Bot commented May 29, 2026 •

edited

Loading